home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 5 / Amiga Tools 5.iso / tools / monitors / restracker / rt.doc < prev    next >
Text File  |  1996-07-16  |  8KB  |  162 lines
  1. rt.doc
  2.  
  3. NAME
  4.      rt - enable resource tracking
  5.  
  6. VERSION
  7.      V0.1b - 12-07-96
  8.  
  9. SYNOPSIS
  10.      rt Config/A,Debug/S
  11.  
  12. REQUIREMENTS
  13.      - AmigaOS 3.0 (V39) or higher
  14.      - a basic 68000 system should run rt alright, but it increases the OS
  15.        overhead, so a 68020 or better is recommended
  16.  
  17. OPTIONS
  18.      Config/A : This parameter is required. It specifies the config file
  19.                 from which rt should read its patching info.
  20.      Debug/S  : Specifying this switch makes rt print a lot of garbage
  21.                 (also called "debugging information") while parsing the
  22.                 config file and doing its patchwork. Without the Debug
  23.                 switch, only error messages are printed.
  24.  
  25. DESCRIPTION
  26.      "rt" is an attempt at resource tracking on AmigaOS. This means the
  27.      system manages lists of all sorts of resources that are currently
  28.      allocated. If a task dies, its resources can be given back to the
  29.      system. UNIX is very good at this, mainly due to its virtual memory
  30.      system you can kill a task and in most cases it gives back everything
  31.      it ever allocated. Although a couple of approaches have been made in
  32.      the last years, AmigaOS still has a lot of problems with it. Resource
  33.      tracking was left out of the first AmigaOS versions for performance
  34.      and memory reasons but still wasn't added later when CPU power and RAM
  35.      prices would have made it possible. Probably Commodore noticed it
  36.      would become hacky :-)
  37.      Compared to other systems of the sort, rt has the advantage of being
  38.      able to patch virtually any OS function. Everything it needs to know
  39.      it reads from a config file, so new resources can be added to the
  40.      tracker without doing any coding.
  41.      See techinfo.doc for detailed info on how the program works!
  42.      Simply spoken, rt manages a couple of lists containing deallocation
  43.      info for every tracked resource. Every resource to be tracked has to
  44.      be specified on a line in the config file. The ReadArgs template for
  45.      these lines is as follows:
  46.  
  47.      Library/A,AllocOff/N/A,FreeOff/N/A,AllocReg/A,SaveAfter/N/A,
  48.      ErrorVal/N/A,FreeReg/A,Resources/N/A,DescOffset/N/A
  49.  
  50.      The parameters in detail:
  51.      Library   : name of the library to be patched
  52.      AllocOff  : LVO of the allocation function (positive)
  53.      FreeOff   : LVO of the deallocation function (positive)
  54.      AllocReg  : the register to get the resource pointer from
  55.                  in the allocation function
  56.      SaveAfter : "0" to save the given register before allocation
  57.                  "1" to save after allocation
  58.      ErrorVal  : return value to consider an allocation failure
  59.      FreeReg   : register where to pass the resource pointer to the
  60.                  deallocation function
  61.      Resources : estimated number of open resources under rt control
  62.                  in normal system operation. This number is not really
  63.                  important, it just increases efficiency if you get it
  64.                  right.
  65.      DescOffset: Structure offset of a pointer to a descriptive string
  66.                  inside the resource structure.
  67.      See the example if you don't really know what all this crap means :-)
  68.      Here it is:
  69.  
  70. EXAMPLE
  71.      Say you want to track all screens. The "allocation function" for
  72.      screens resides in intuition.library and is called
  73.      OpenScreenTagList(). There's also an old function called OpenScreen()
  74.      for compatibility with pre-2.0 software but the TagList version is
  75.      used much more often in times OS3.0 (OpenScreen() may be patched
  76.      separately). Deallocation is done by CloseScreen() in the same
  77.      library. Now grab your favorite FD parser and determine these
  78.      functions' LVOs (this will probably become easier if I decide to add
  79.      an own FD parser to rt). They're -612 and -66 respectively here. We
  80.      now have the first three parameters in the configfile line:
  81.      intuition.library 612 66
  82.      Notice the lacking  sign - all LVOs are negative so the minus was
  83.      omitted.
  84.      Next is "AllocReg" and "SaveAfter" - the register where we're going
  85.      to find a pointer to the resource before or after the allocation
  86.      function - and the time when to save this register to the
  87.      ResourceNode. The AutoDocs tell you that OpenScreenTagList() returns a
  88.      pointer to the screen structure in d0 which means we have to save d0
  89.      *after* the OpenScreenTagList() call. That's our next two config
  90.      parameters:
  91.      intuition.library 612 66 d0 1
  92.      But we need to tell the patch when to add a resource to the
  93.      "allocated" list - that is, if the allocation really succeeded.
  94.      That's what the parameter "ErrorVal" does. Consulting the AutoDocs
  95.      again tells you that OpenScreenTagList() returns a NULL pointer to
  96.      indicate an error. Currently rt can only check a returncode in
  97.      register d0, no matter which register will be saved as the resource
  98.      pointer, which should be OK for most functions but will probably be
  99.      extended to support whole ranges of errorvalues and different
  100.      registers. OK, this NULL pointer is our errorvale, which makes the
  101.      config line:
  102.      intuition.library 612 66 d0 1 0
  103.      The parameter "FreeReg" works just like AllocReg - it specifies the
  104.      register where the deallocation function expects the resource pointer.
  105.      In our case, this is a0 - guess what, that's from the AutoDocs!
  106.      The last two parameters are the most confusing ones :-) :
  107.      "Resources" gives the estimated number of resources of this type that
  108.      are under control of rt in normal system operation. This number is not
  109.      critical at all but the better it fits the more efficient rt will run.
  110.      Too high values will waste memory (not much though, if you specify 100
  111.      resources but normally use only 20, you'll have wasted
  112.      (100-20)*16=1280 bytes), too low values will slow rt down a tiny bit
  113.      and increase memory fragmentation.
  114.      For the technically interested: Resources * sizeof(RsrcNode) is the
  115.      pool size for the function's private memory pool.
  116.      For screens, a sensible value is ~5-10. You'll seldom have more than
  117.      5 screens open and hardly ever 10.
  118.      "DescOffset" is the offset into a resource structure where a pointer
  119.      to a descriptive string can be found. A lot of resources have such
  120.      strings - screens and windows have a title-text, libraries and devices
  121.      have a name pointed to by their Node field etc. The rtFreeresources
  122.      program uses this field to give you a more information about a
  123.      specific resource when asking you whether to free it or not.
  124.      For Screens, the pointer to the title-text can be found in the screen
  125.      structure at offset 22. If your resource has no such string (like
  126.      AmigaDOS filehandles for example), enter a zero here.
  127.      That completes the configfile line:
  128.      intuition.library 612 66 d0 1 0 a0 10 22
  129.  
  130. BUGS
  131.      - An allocation function can only have a single errorvalue in d0.
  132.      - The config file parser is not very smart.
  133.      - Not enough sanity checks for the config. Be careful what you patch!
  134.      - Some functions may not be patched at all. This is not really a bug
  135.        but an (IMHO) inevitable weakness of the concept. These functions
  136.        include:
  137.        - Most memory allocation functions (AllocMem()/FreeMem()/
  138.          AllocPooled()/FreePooled()). AllocVec()/FreeVec() and
  139.          AllocRemember()/FreeRemember() might work though.
  140.        - functions that are legal to call from interrupts (signalling etc.)
  141.          As these function seldom allocate stuff this shouldn't really be
  142.          a problem.
  143.      - Well, it's a beta... 8-)
  144.  
  145. HISTORY
  146.      V0.1b  (12-07-96): First Release
  147.  
  148. TODO
  149.      - implement more versatile error checks for alloc function
  150.      - FD-file parser to calculate LVOs from function names in the cfg file
  151.      - better docs (AmigaGuide)
  152.      - include predefined functions to install via configfile-macro
  153.  
  154. AUTHOR
  155.      Matthias Bethke
  156.      Giessener Strasse 31
  157.      35457 Lollar
  158.      Germany
  159.      AmigaNet : Matthias Bethke@39:176/208.0
  160.        Usenet : postmaster@sweetdreams.lahn.de
  161.            or : Matthias.Bethke@sowi.uni-giessen.de
  162.